openapi: 3.1.0
info:
  title: Wia REST API reference
  description: >-
    </br>A REST API to interact with Wia platform to enable external
    applications to analyse energy consumption and to automate internal
    operations relating to the capturing and grouping of energy consumption.
    </br> </br> To get started, please ensure you have the correct permissions
    and appropriate key. If you have not been provided a key, please contact
    your representative.  </br> </br> The API is organised around REST. Our API
    has predictable resource-oriented URLs, accepts form-encoded request bodies,
    returns JSON-encoded responses, and uses standard HTTP response codes,
    authentication, and verbs.
  version: v1
components:
  securitySchemes:
    ApplicationKey:
      type: http
      description: An Application key for read only access
      scheme: bearer
      bearerFormat: Bearer
  parameters:
    id:
      name: id
      description: Id of Object
      in: path
      required: true
      schema:
        type: string
    spaceId:
      name: space.id
      description: Id of Space
      in: query
      schema:
        type: string
    spaceIdNotRequired:
      name: space.id
      description: Id of Space
      in: query
      required: false
      schema:
        type: string
    organisationId:
      name: organisation.id
      description: Id of Organisation
      in: query
      required: false
      schema:
        type: string
    deviceId:
      name: device.id
      description: Id of Device
      in: query
      required: false
      schema:
        type: string
    gatewayId:
      name: gateway.id
      description: Id of Gateway
      in: query
      required: false
      schema:
        type: string
    flowId:
      name: flow.id
      description: Id of Flow
      in: query
      required: false
      schema:
        type: string
    productId:
      name: product.id
      description: Id of Product
      in: query
      required: false
      schema:
        type: string
    alertRuleId:
      name: alertRule.id
      description: Id of Alert Rule
      in: query
      required: false
      schema:
        type: string
    placeId:
      name: place.id
      description: Id of Place
      in: query
      required: false
      schema:
        type: string
    batchNumber:
      name: batchNumber
      description: batchNumber of Device
      in: query
      required: false
      schema:
        type: string
    resourceType:
      name: resourceType
      description: Type of Resource
      in: query
      required: false
      schema:
        type: string
        enum:
          - device
          - place
          - space
    limit:
      name: limit
      in: query
      description: Max number of rows to return
      required: false
      schema:
        type: integer
        format: int32
        example: 20
    page:
      name: page
      in: query
      description: Section of rows to return e.g. 0, 1 or 2
      required: false
      schema:
        type: integer
        format: int32
    sort:
      name: sort
      in: query
      description: 'Sort by Ascending or Descending order Default: DESC'
      required: false
      schema:
        type: string
        enum:
          - ASC
          - DESC
    order:
      name: order
      in: query
      description: Order by column e.g. id
      required: false
      schema:
        type: string
    since:
      name: since
      in: query
      description: Retrieve from this timestamp onwards
      required: false
      schema:
        oneOf:
          - type: string
            format: date-time
            example: '2022-01-01T00:00:00Z'
          - type: integer
            example: 1640995200000
    until:
      name: until
      in: query
      description: Retrieve until this timestamp
      required: false
      schema:
        oneOf:
          - type: string
            format: date-time
            example: '2022-01-01T00:00:00Z'
          - type: integer
            example: 1640995200000
    continuationToken:
      name: continuationToken
      in: query
      description: The continuation token to retrieve the next set of data.
      required: false
      schema:
        type: string
  schemas:
    Alert:
      type: object
      properties:
        id:
          type: string
          example: alt_abcdef12345678
        event:
          $ref: '#/components/schemas/Event'
        note:
          type: string
          example: A window was opened
        resolvedAt:
          type: string
          format: date-time
          example: 1642759067045
        acknowledgedAt:
          type: string
          format: date-time
          example: 1642759067045
        firstSeenAt:
          type: string
          format: date-time
          example: 1642759067045
        lastSeenAt:
          type: string
          format: date-time
          example: 1642759067045
        device:
          $ref: '#/components/schemas/Device'
        gateway:
          $ref: '#/components/schemas/Gateway'
        alertRule:
          $ref: '#/components/schemas/AlertRule'
        createdAt:
          type: integer
          example: 1642759067045
        updatedAt:
          type: integer
          example: 1642759067045
    AlertRule:
      type: object
      properties:
        id:
          type: string
          example: alt_abcdef12345678
        name:
          type: string
          example: Gateway offline
        type:
          type: string
          example: email
        severity:
          type: string
          example: high
        enabled:
          type: boolean
          example: true
        autoResolve:
          type: boolean
          example: false
        config:
          type: object
          example: {}
        organisation:
          $ref: '#/components/schemas/Organisation'
        product:
          $ref: '#/components/schemas/Product'
        space:
          $ref: '#/components/schemas/Space'
        notificationTemplate:
          $ref: '#/components/schemas/NotificationTemplate'
        createdAt:
          type: integer
          example: 1642759067045
        updatedAt:
          type: integer
          example: 1642759067045
    NotificationTemplate:
      type: object
      properties:
        id:
          type: string
          example: nt_abcdef12345678
        title:
          type: string
          example: Email template
        type:
          type: string
          example: email
        body:
          type: string
          example: Email body
        webhookUrl:
          type: string
          example: www.webhook-example.com
        webhookHeaders:
          type: object
          example: {}
        config:
          type: object
          example: {}
        createdAt:
          type: integer
          example: 1642759067045
        updatedAt:
          type: integer
          example: 1642759067045
    ApiKey:
      type: object
      properties:
        secretKey:
          type: string
          example: d_sk_abc123def45678
        createdAt:
          type: integer
          example: 1642759067045
    Device:
      type: object
      properties:
        id:
          type: string
          example: dev_abc123
        isMain:
          type: boolean
          example: true
        name:
          type: string
          example: Test Device
        customId:
          type: string
          example: custom-id
        serialNumber:
          type: string
          example: abc12345678
        batchNumber:
          type: string
          example: '123'
        space:
          $ref: '#/components/schemas/Space'
        product:
          $ref: '#/components/schemas/Product'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        location:
          $ref: '#/components/schemas/Location'
        state:
          type: object
        meta:
          type: object
        wifi:
          type: object
          properties:
            macAddress:
              type: string
              example: 00:00:00:B5:D5:A5
            rssi:
              type: integer
              example: -90
        cellular:
          type: object
          properties:
            network:
              type: string
              example: vodafone
            rssi:
              type: integer
              example: -67
            imei:
              type: string
              example: 10A12345677890
            iccid:
              type: string
              example: 891004234814455936F
        bluetooth:
          type: object
          properties:
            macAddress:
              type: string
              example: 00:00:00:B5:D5:A5
            rssi:
              type: integer
              example: -90
        lora:
          type: object
          properties:
            devEui:
              type: string
              example: 10A12345678910234
            devAddr:
              type: string
              example: 10A123456
            appEui:
              type: string
              example: 10A12345678910234567890
            appKey:
              type: string
              example: 1234404C696E6B4C6F52613230313823
        sigfox:
          type: object
          properties:
            id:
              type: string
              example: 123456AD
        lastSeenAt:
          type: integer
          example: 1631707207000
        lastUnprocessedEventTimestamp:
          type: integer
          example: 1631707207000
        lastProcessedEventTimestamp:
          type: integer
          example: 1631707207000
        createdAt:
          type: integer
          example: 1631707207000
        updatedAt:
          type: integer
          example: 1631707207000
    Event:
      type: object
      properties:
        id:
          type: string
          example: 1234-abcd-5678-efgh
        name:
          type: string
          example: Test Event
        data:
          type: object
          example:
            test: true
        timestamp:
          type: integer
          example: 1631707200000
    Electricity:
      type: object
      required:
        - result
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/EnergyReading'
        continuationToken:
          type:
            - string
            - 'null'
          example: eyJ0bpo92Dd2twl7ko1=
      oneOf:
        - $ref: '#/components/schemas/EnergyDeviceReadings'
        - $ref: '#/components/schemas/EnergyCountryReadings'
    EnergyReading:
      type: object
      properties:
        energy:
          type: string
          example: '1000'
        timestamp:
          type: integer
          example: 1631707200000
    EnergyDeviceReadings:
      type: object
      properties:
        devices:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EnergyReadingArray'
          example:
            dev_abc123:
              - energy: '1000'
                timestamp: 1631707200000
            dev_def456:
              - energy: '2000'
                timestamp: 1631707200000
    EnergyCountryReadings:
      type: object
      properties:
        countries:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EnergyReadingArray'
          example:
            IRL:
              - energy: '1000'
                timestamp: 1631707200000
            DEU:
              - energy: '2000'
                timestamp: 1631707200000
    EnergyReadingArray:
      type: array
      items:
        $ref: '#/components/schemas/EnergyReading'
    Gas:
      type: object
      required:
        - result
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/GasReading'
        continuationToken:
          type:
            - string
            - 'null'
          example: eyJ0bpo92Dd2twl7ko1=
      oneOf:
        - $ref: '#/components/schemas/GasDeviceReadings'
        - $ref: '#/components/schemas/GasCountryReadings'
    GasReading:
      type: object
      properties:
        energy:
          type: string
          example: '1000'
        timestamp:
          type: integer
          example: 1631707200000
    GasDeviceReadings:
      type: object
      properties:
        devices:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GasReadingArray'
          example:
            dev_abc123:
              - gas: '1000'
                timestamp: 1631707200000
            dev_def456:
              - gas: '2000'
                timestamp: 1631707200000
    GasCountryReadings:
      type: object
      properties:
        countries:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GasReadingArray'
          example:
            IRL:
              - gas: '1000'
                timestamp: 1631707200000
            DEU:
              - gas: '2000'
                timestamp: 1631707200000
    GasReadingArray:
      type: array
      items:
        $ref: '#/components/schemas/GasReading'
    Gateway:
      type: object
      properties:
        id:
          type: string
          example: gty_123abc456
        serialNumber:
          type: string
          example: abc_23243456
        name:
          type: string
          example: Test Gateway
        product:
          type: object
          properties:
            id:
              type: string
              example: pro_abcdef123
        isOnline:
          type: boolean
          example: true
        lora:
          type: object
          properties:
            gatewayId:
              type: string
              example: 123abc456def
        lastSeenAt:
          type: integer
          example: 1631707207000
    Location:
      type: object
      properties:
        id:
          type: string
          example: 1234-abcd-5678-efgh
        latitude:
          type: string
          example: '4.67'
        longitude:
          type: string
          example: '54.2'
        altitude:
          type: string
          example: '1.23'
        timestamp:
          type: integer
          example: 1631707200000
    Organisation:
      type: object
      properties:
        id:
          type: string
          example: org_123abc456def
        name:
          type: string
          example: Test Organisation
    Product:
      type: object
      properties:
        id:
          type: string
          example: pro_abc123def
        name:
          type: string
          example: Test Product
        description:
          type: string
          example: This is a Test Product
        manufacturer:
          type: string
          example: Wia
        model:
          type: string
          example: v1
        colour:
          type: string
          example: '#2E7DFF'
        category:
          type: string
          example: test
        image:
          type: string
          example: 7170506d-5759-400e-a5d1-073c5d175abc
        state:
          type: object
          example:
            state1: true
    Place:
      type: object
      properties:
        id:
          type: string
          example: wpl_abc123def
        name:
          type: string
          example: Test Workplace
        state:
          type: object
          example:
            state1: true
        config:
          type: object
          example:
            capacity: 50
            squareMeters: 500
            maxAllowableHeadcount: 100
            currentAllocatedHeadcount: 80
    Space:
      type: object
      properties:
        id:
          type: string
          example: spc_abc123
        name:
          type: string
          example: Test Space
        isPublic:
          type: boolean
          example: false
        disabled:
          type: boolean
          example: false
        avatar:
          type: object
          properties:
            default:
              type: string
              example: 1234-5342-5543-36AD
            url:
              type: string
              example: https://example.com/image
            thumbnail:
              type: string
              example: 1234-5342-5543-36AD
        owner:
          type: object
          properties:
            organisation:
              $ref: '#/components/schemas/Organisation'
    Water:
      type: object
      required:
        - result
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/WaterReading'
        continuationToken:
          type:
            - string
            - 'null'
          example: eyJ0bpo92Dd2twl7ko1=
      oneOf:
        - $ref: '#/components/schemas/WaterDeviceReadings'
        - $ref: '#/components/schemas/WaterCountryReadings'
    WaterReading:
      type: object
      properties:
        water:
          type: string
          example: '1000'
        timestamp:
          type: integer
          example: 1631707200000
    WaterDeviceReadings:
      type: object
      properties:
        devices:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/WaterReadingArray'
          example:
            dev_abc123:
              - water: '1000'
                timestamp: 1631707200000
            dev_def456:
              - water: '2000'
                timestamp: 1631707200000
    WaterCountryReadings:
      type: object
      properties:
        countries:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/WaterReadingArray'
          example:
            IRL:
              - water: '1000'
                timestamp: 1631707200000
            DEU:
              - water: '2000'
                timestamp: 1631707200000
    WaterReadingArray:
      type: array
      items:
        $ref: '#/components/schemas/WaterReading'
  responses:
    NotFound:
      description: The specified resource was not found.
    BadRequest:
      description: Bad Request.
    Unauthorised:
      description: Unauthorised.
    ServerError:
      description: Server Error.
servers:
  - url: https://api.wia.io/v1
    description: Production
paths:
  /alerts:
    get:
      tags:
        - Alert
      security:
        - ApplicationKey: []
      description: Retrieves a list of alerts in a Space
      parameters:
        - name: unresolved
          description: Returns only unresolved alerts
          in: query
          schema:
            type: boolean
        - name: resolved
          description: Returns only resolved alerts
          in: query
          schema:
            type: boolean
        - $ref: '#/components/parameters/organisationId'
        - $ref: '#/components/parameters/productId'
        - $ref: '#/components/parameters/spaceId'
        - $ref: '#/components/parameters/alertRuleId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/since'
        - $ref: '#/components/parameters/until'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /alerts/{id}:
    get:
      tags:
        - Alert
      security:
        - ApplicationKey: []
      description: Retrieves an alert
      parameters:
        - name: id
          description: Id of the alert
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /alerts/{id}/resolve:
    put:
      tags:
        - Alert
      security:
        - ApplicationKey: []
      description: Update the resolution status of an alert
      parameters:
        - name: id
          description: Id of the alert
          in: path
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              properties:
                resolvedAt:
                  type: number
                acknowledgedAt:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /devices:
    get:
      tags:
        - Device
      security:
        - ApplicationKey: []
      description: >-
        Retrieves a list of devices in a Model e.g. Device, Gateway, Flow,
        Workplace, Space, Organisation, Product, User, etc.
      parameters:
        - $ref: '#/components/parameters/spaceIdNotRequired'
        - $ref: '#/components/parameters/placeId'
        - $ref: '#/components/parameters/gatewayId'
        - $ref: '#/components/parameters/productId'
        - $ref: '#/components/parameters/organisationId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /devices/{id}:
    get:
      tags:
        - Device
      security:
        - ApplicationKey: []
      description: Retrieve a Device
      parameters:
        - name: id
          description: Id of the device
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /energy/electricity:
    get:
      tags:
        - Energy
      security:
        - ApplicationKey: []
      description: >-
        The API endpoint retrieves electricity consumption data in
        kilowatt-hours (kWh) from electricity meters. <br /> <br /> The endpoint
        utilizes the underlying data from the meters to calculate and return the
        energy consumed by a customer during a given time period.<br /><br /> To
        use the API endpoint, the user will need to provide the necessary
        information, such as the date range for which they wish to retrieve
        data, the device id or space id to which a group of devices belong, and
        any other relevant parameters. <br /><br /> The endpoint will then
        gather underlying stores of meter readings and calculate the total
        energy consumed by the customer for a specified time resolution <br />
        <br /> The energy consumption data will be returned in kWh, which is the
        standard unit of measurement for electricity consumption and the time
        units are in UTC. <br /> <br /> If the metres use current usage to read
        energy consumption, that is also outputted by the API endpoint with the
        same format as power consumption. <br /> <br /> This API endpoint can be
        useful for a variety of applications, such as tracking energy usage for
        billing purposes, identifying energy-saving opportunities, and
        monitoring energy usage for sustainability initiatives. <br />
      parameters:
        - $ref: '#/components/parameters/spaceIdNotRequired'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/since'
        - $ref: '#/components/parameters/until'
        - $ref: '#/components/parameters/continuationToken'
        - name: timezone
          in: query
          description: >
            The timezone to use for the data retrieval.

            If not specified, the timezone will be set to Space timezone offset
            to UTC.
          required: false
          schema:
            type: string
            example: Europe/London
        - name: interval
          in: query
          description: |
            Interval for the data aggregation in the format number unit,
            where unit can be 'minute', 'hour', 'day', 'week', or 'month'.
          required: false
          schema:
            type: string
            pattern: ^\d+\s+(minute|hour|day|week|month)$
            default: 1 hour
            example: 2 hours
        - name: breakdown
          in: query
          description: |
            The breakdown of the data to retrieve. If not specified,
            the data will be retrieved for the entire organisation.
          required: false
          schema:
            type: string
            enum:
              - device
              - country
        - name: current
          in: query
          description: |
            The current time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
        - name: previous
          in: query
          description: |
            The previous time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
        - name: source
          in: query
          description: |
            The source of the data to retrieve. Where its grid, solar or wind.
          required: false
          schema:
            type: string
            enum:
              - grid
              - solar
              - wind
        - name: flow
          in: query
          description: |
            Whether the energy usage is consumed or produced.
          required: false
          schema:
            type: string
            enum:
              - consumption
              - production
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Electricity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /energy/gas:
    get:
      tags:
        - Energy
      security:
        - ApplicationKey: []
      description: >-
        The API endpoint retrieves Gas consumption data in (m³) from gas meters.
        <br /> <br /> The endpoint utilizes the underlying data from the meters
        to calculate and return the gas consumed by a customer during a given
        time period.<br /><br /> To use the API endpoint, the user will need to
        provide the necessary information, such as the date range for which they
        wish to retrieve data, the device id or space id to which a group of
        devices belong, and any other relevant parameters. <br /><br /> The
        endpoint will then gather underlying stores of meter readings and
        calculate the total gas consumed by the customer during the specified
        time period such as  15 minutes, 2 hours, 1 day etc. <br /> <br /> The
        gas consumption data will be returned in m³, which is the standard unit
        of measurement for gas consumption and the time units are in UTC. <br />
        <br /> This API endpoint can be useful for a variety of applications,
        such as tracking gas usage for billing purposes, identifying consumption
        saving opportunities, and monitoring usage for sustainability
        initiatives. <br />
      parameters:
        - $ref: '#/components/parameters/spaceIdNotRequired'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/since'
        - $ref: '#/components/parameters/until'
        - $ref: '#/components/parameters/continuationToken'
        - name: interval
          in: query
          description: |
            Interval for the data aggregation in the format number unit,
            where unit can be 'minute', 'hour', 'day', 'week', or 'month'.
          required: false
          schema:
            type: string
            pattern: ^\d+\s+(minute|hour|day|week|month)$
            default: 1 hour
            example: 2 hours
        - name: breakdown
          in: query
          description: |
            The breakdown of the data to retrieve. If not specified,
            the data will be retrieved for the entire organisation.
          required: false
          schema:
            type: string
            enum:
              - device
              - country
        - name: current
          in: query
          description: |
            The current time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
        - name: previous
          in: query
          description: |
            The previous time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gas'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /energy/water:
    get:
      tags:
        - Energy
      security:
        - ApplicationKey: []
      description: >-
        The API endpoint retrieves Water consumption data in (m³) from water
        meters. <br /> <br /> The endpoint utilizes the underlying data from the
        meters to calculate and return the water consumed by a customer during a
        given time period.<br /><br /> To use the API endpoint, the user will
        need to provide the necessary information, such as the date range for
        which they wish to retrieve data, the device id or space id to which a
        group of devices belong, and any other relevant parameters. <br /><br />
        The endpoint will then gather underlying stores of meter readings and
        calculate the total water consumed by the customer during the specified
        time period such as  15 minutes, 2 hours, 1 day etc. <br /> <br /> The
        water consumption data will be returned in m³, which is the standard
        unit of measurement for water consumption and the time units are in UTC.
        <br /> <br /> This API endpoint can be useful for a variety of
        applications, such as tracking water usage for billing purposes,
        identifying consumption saving opportunities, and monitoring usage for
        sustainability initiatives. <br />
      parameters:
        - $ref: '#/components/parameters/spaceIdNotRequired'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/since'
        - $ref: '#/components/parameters/until'
        - $ref: '#/components/parameters/continuationToken'
        - name: timezone
          in: query
          description: >
            The timezone to use for the data retrieval.

            If not specified, the timezone will be set to Space timezone offset
            to UTC.
          required: false
          schema:
            type: string
            example: Europe/London
        - name: interval
          in: query
          description: |
            Interval for the data aggregation in the format number unit,
            where unit can be 'minute', 'hour', 'day', 'week', or 'month'.
          required: false
          schema:
            type: string
            pattern: ^\d+\s+(minute|hour|day|week|month)$
            default: 1 hour
            example: 2 hours
        - name: breakdown
          in: query
          description: |
            The breakdown of the data to retrieve. If not specified,
            the data will be retrieved for the entire organisation.
          required: false
          schema:
            type: string
            enum:
              - device
              - country
        - name: current
          in: query
          description: |
            The current time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
        - name: previous
          in: query
          description: |
            The previous time period to retrieve data for.
            When specified, the return timestamps
            will be aligned to time period for each timezone in UTC.
          required: false
          schema:
            type: string
            enum:
              - hour
              - day
              - week
              - month
              - year
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /gateways/:
    get:
      tags:
        - Gateway
      security:
        - ApplicationKey: []
      description: List Gateways
      parameters:
        - $ref: '#/components/parameters/spaceIdNotRequired'
        - $ref: '#/components/parameters/organisationId'
        - $ref: '#/components/parameters/productId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Gateway'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /gateways/{id}:
    get:
      tags:
        - Gateway
      security:
        - ApplicationKey: []
      description: Retrieve a Gateway
      parameters:
        - name: id
          description: Id of the Gateway
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gateway'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /spaces:
    get:
      tags:
        - Space
      security:
        - ApplicationKey: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
        - name: country
          description: ISO 3166-1 alpha-3 country code
          in: query
          schema:
            type: string
            pattern: ^[A-Z]{3}$
          required: false
      description: Retrieve list of all Spaces
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Space'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /spaces/{id}:
    get:
      tags:
        - Space
      security:
        - ApplicationKey: []
      description: Retrieve a Space
      parameters:
        - name: id
          description: Id of the space
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Space'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
tags:
  - name: Alert
    description: >-
      Alerts provide information about devices that have gone offline or
      exhibited anomalies in their data, helping to monitor system health and
      identify potential issues. </br> Alerts can be resolved by acknowledging
      them, and can be filtered by their resolution status.
  - name: Device
    description: >-
      Devices are a representation of objects that are connected to the Wia
      platform and can be used to collect data from the environment. The objects
      can be physical sensors, cloud integrations or manual uploads.
  - name: Energy
    description: >-
      Energy consumption data is used to track the amount of energy used by a
      customer over a given time period. </br> The data can be used to identify
      energy-saving opportunities, monitor energy usage for sustainability
      initiatives, and track energy usage for billing purposes.
  - name: Gateway
    description: >-
      Gateways are devices that connect to the Wia platform and are used to
      transport data from other devices in the environment to the Wia platform.
  - name: Space
    description: >-
      Spaces are physical locations that are monitored by the Wia platform and
      house all devices and gateways that represent that location.
